home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
FishMarket 1.0
/
FishMarket v1.0.iso
/
fishies
/
351-375
/
disk_368
/
popmenu
/
popmenu_pak.doc
< prev
next >
Wrap
Text File
|
1992-05-06
|
12KB
|
427 lines
TABLE OF CONTENTS
popmenu_pak/BuildPMenu
popmenu_pak/CountPMenuItems
popmenu_pak/FreePMenu
popmenu_pak/GetPItem
popmenu_pak/GetPItemNum
popmenu_pak/HandlePMenu
popmenu_pak/InitPMenu
popmenu_pak/RefreshPMenu
popmenu_pak/RemovePMenu
popmenu_pak/SetActiveItem
popmenu_pak/SetPMenuColor
popmenu_pak/SetPMenuText
popmenu_pak/BuildPMenu popmenu_pak/BuildPMenu
NAME
BuildPMenu - Allocate a PMenu structure and setup its data
SYNOPSIS
pmenu = BuildPMenu(first_item, flags, active, title, id);
PROTOTYPE
struct PMenu *BuildPMenu(struct PMenuItem *, USHORT, SHORT, UBYTE *,
USHORT);
FUNCTION
BuildPMenu allocates and sets up a PMenu structure and necessary
support structures, such as the PMenu Gadget, IntuiText, and Border.
If a title is supplied, the PMenu always displays the title in the
menu select box, otherwise the last selected menu item is displayed.
The specified ID is used to compare with that of the ID found when
a GADGETDOWN message is received from the application program. The
active menu item number is a number from 1 up to the number of items
in the PMenuItem list, optionally passed as the first parameter. This
tells InitPMenu() which menu item to display when the menu is first
initialized (of course, this has no effect if a title is used). Note
that the first item need not be passed to this function. If you are
dynamically allocating your PMenuItems, then they can be added manually
later, with an assignment such as: "pmenu->FirstPItem = first_item".
INPUTS
first_item -- pointer to a prepared PMenuItem structure, initialized
with the following data:
------------------------
NextPItem - pointer to next PMenuItem
Flags - flags defining rendering of item
MutualExclude - items of a LIST menu deselected when this one is
ItemFill - pointer to item IntuiText or imagery (text only)
SelectFill - pointer to selected item or imagery (not supported)
flags -- flags defining type and rendering of menu:
LISTPMENU - not supported
COMMPMENU - normal command-type menu
SHADOWED - draw a shadow around the menu button
TITLED - if title is to be used later, but isn't
passed with this call
active -- number (1-n) of active item (0 = first one too)
title -- pointer to UBYTE constant title (or NULL)
id -- PMenu ID, used to decide which PMenu was selected
RETURNS
Returns a pointer to the allocated PMenu is successful, otherwise NULL.
BUGS
None.
SEE ALSO
InitPMenu(), FreePMenu()
popmenu_pak/CountPMenuItems popmenu_pak/CountPMenuItems
NAME
CountPMenuItems - count the number of menu items within a PopMenu
SYNOPSIS
items = CountPMenuItems(pmenu);
PROTOTYPE
int CountPMenuItems(struct PMenu *);
FUNCTION
CountPMenuItems traverses the PopMenu PMenuItem list, and counts all
of the items in the list. This is useful to the application program
if it needs to know how many items are in a PMenu for window size
adjusting purposes.
INPUTS
pmenu -- pointer to a prepared PMenu structure
RETURNS
The number of items in the PMenu Item list, or zero if no items have
been assigned yet.
BUGS
None.
SEE ALSO
popmenu_pak/FreePMenu popmenu_pak/FreePMenu
NAME
FreePMenu - removes and deallocates a PopMenu
SYNOPSIS
FreePMenu(pmenu);
PROTOTYPE
void FreePMenu(struct PMenu *);
FUNCTION
FreePMenu first calls RemovePMenu() to remove the specified PopMenu
from its window. It then deallocates all memory used by the PopMenu,
that was allocated by BuildPMenu(). FreePMenu() can be called after
RemovePMenu() without screwing up anything.
INPUTS
pmenu -- pointer to the prepared PMenu to deallocate
RETURNS
None.
BUGS
None.
SEE ALSO
BuildPMenu(), RemovePMenu()
popmenu_pak/GetPItem popmenu_pak/GetPItem
NAME
GetPItem - return a pointer to the numbered PMenuItem
SYNOPSIS
pmenuitem = GetPItem(pmenu, item_number);
PROTOTYPE
struct PMenuItem *GetPItem(struct PMenu *, SHORT);
FUNCTION
GetPItem searches the specified PMenu's item list until it gets to the
specified item number, then returns the PMenuItem's pointer.
INPUTS
pmenu -- pointer to a prepared PMenu structure
item_number -- item number of PMenuItem pointer to return
RETURNS
Pointer to the specified PMenuItem if that item number exists,
otherwise NULL.
BUGS
None.
SEE ALSO
GetPItemNum()
popmenu_pak/GetPItemNum popmenu_pak/GetPItemNum
NAME
GetPItemNum - find the specified PMenuItem's item number
SYNOPSIS
item_number = GetPItemNum(pmenu, item);
PROTOTYPE
SHORT GetPItemNum(struct PMenu *, struct PMenuItem *);
FUNCTION
GetPItemNum returns the item number of the specfied PMenuItem within
the specified PMenu.
INPUTS
pmenu -- pointer to a prepared PMenu structure
item -- pointer to an existing PMenuItem
RETURNS
The item number of the PMenuItem, if it is within the PMenu, otherwise
NULL.
BUGS
None.
SEE ALSO
GetPItem()
popmenu_pak/HandlePMenu popmenu_pak/HandlePMenu
NAME
HandlePMenu - draw the PMenu and get an item from the user
SYNOPSIS
item_number = HandlePMenu(pmenu);
PROTOTYPE
USHORT HandlePMenu(struct PMenu *);
FUNCTION
HandlePMenu opens and draws the specified PMenu's items. Then it goes
into a mode where it waits for a MOUSEBUTTON:SELECTUP event, waiting
for the user to lift up on the left mouse button. During this time it
tracks the mouse over the menu items, highlighted enabled menu items.
When the mouse button is released, HandlePMenu() returns the item
number of the item the mouse was over when the button was released. If
the mouse was outside the window, then 0 is returned. This function is
called by the host application program when it receives a GADGETDOWN
event, and the ID number of the selected Gadget and the ID of a PMenu
are the same. The host casts the pointer of the Gadget's UserData field
to type (struct PMenu *), and passes this to HandlePMenu().
NOTE: If you have several overlapping, call WindowToFront() on the
window containing the selected PMenu before calling HandlePMenu(). This
makes sure the window is front (and has no possibly-wreckable clipping
rectangles) and won't get messed up by the BitMap operations done by
HandlePMenu().
INPUTS
pmenu -- pointer to an initialized PMenu structure.
RETURNS
Item number of selected item (1-n), or NULL if none selected.
BUGS
No layer locking or menu clip-recting is done on the menu drawing or
un-drawing. The menu is rendered directly in the window's BitMap,
after a backup of the menu area is saved.
SEE ALSO
popmenu_pak/InitPMenu popmenu_pak/InitPMenu
NAME
InitPMenu - attach a PMenu to a window
SYNOPSIS
success = InitPMenu(window, pmenu, x, y);
PROTOTYPE
int InitPMenu(struct Window *, struct PMenu *, SHORT, SHORT);
FUNCTION
InitPMenu computes the size of the specified PopMenu and then attaches
it to the specified window at the specified location, displaying the
application-specified title (set with BuildPMenu() or SetPMenuText())
or default menu item name. If negative values are used for the x or y
position of the menu, then they will be offsets from the right or
bottom border of the window (such as GRELRIGHT or GRELBOTTOM for
Gadgets). Be careful, as you might not know how wide the menu will be.
If you specify a -1 for the x or y coordinates (or both), then the
menu will be located relative to the right or bottom borders, based
on the computed width/height of the PopMenu, plus 5 pixels. For
example, to place a PopMenu just inside the right border of the window,
pass a -1 for the x coordinate.
INPUTS
window -- pointer to a standard open window
pmenu -- pointer to a previously initialized PMenu structure
x -- x-coordinate of upper-left corner of menu activation gadget
y -- y-coordinate of upper-left corner of menu activation gadget
RETURNS
TRUE if successful, NULL otherwise (only if a Window or PMenu pointer
was not passed).
BUGS
None.
SEE ALSO
BuildPMenu(), HandlePMenu()
popmenu_pak/RefreshPMenu popmenu_pak/RefreshPMenu
NAME
RefreshPMenu - redraws a PopMenu
SYNOPSIS
RefreshPMenu(pmenu);
PROTOTYPE
void RefreshPMenu(struct PMenu *);
FUNCTION
RefreshPMenu redraws the PopMenu selection box and updates the title
in the box for an initialized PopMenu. This is useful if your window
imagery/gadgetry has been trashed by some graphics operation.
InitPMenu() calls RefreshPMenu() for you.
INPUTS
pmenu -- pointer to an initialied PMenu structure
RETURNS
None.
BUGS
None.
SEE ALSO
BuildPMenu(), InitPMenu()
popmenu_pak/RemovePMenu popmenu_pak/RemovePMenu
NAME
RemovePMenu - removes a PMenu from its window
SYNOPSIS
RemovePMenu(pmenu);
PROTOTYPE
void RemovePMenu(struct PMenu *);
FUNCTION
RemovePMenu removes the specified PopMenu imagery from its window, but
does not deallocate the PopMenu data. RemovePMenu() is called by
FreePMenu().
INPUTS
pmenu -- pointer to the PMenu to remove
RETURNS
None.
BUGS
None.
SEE ALSO
InitPMenu(), FreePMenu()
popmenu_pak/SetActiveItem popmenu_pak/SetActiveItem
NAME
SetActiveItem - set a new active menu item for a PopMenu
SYNOPSIS
SetActiveItem(pmenu, item_number);
PROTOTYPE
void SetActiveItem(struct PMenu *, SHORT);
FUNCTION
SetActiveItem sets the specified item number as the current active
menu item, and draws the item text in the menu select box (unless the
menu has been set with a constant title). This only works for menus
of type COMMPMENU.
INPUTS
pmenu -- pointer to the PMenu to affect
item_number -- item number (1-n) of item to make current
RETURNS
None.
BUGS
None.
SEE ALSO
popmenu_pak/SetPMenuColor popmenu_pak/SetPMenuColor
NAME
SetPMenuColor - set the drawing colors of a PopMenu
SYNOPSIS
SetPMenuColor(pmenu, frontpen, backpen);
PROTOTYPE
void SetPMenuColor(struct PMenu *, USHORT, USHORT);
FUNCTION
SetPMenuColor sets the rendering colors of the specified PopMenu to
the specified colors. The frontpen is used as the menu border and
title text color, and the backpen is used for the filled areas within
the menu select box and expanded menu list.
INPUTS
pmenu -- pointer to the initialized PopMenu to affect
frontpen -- color of the PopMenu border and title text
backpen -- color of the PopMenu filled areas
RETURNS
None.
BUGS
None.
SEE ALSO
SetPMenuText()
popmenu_pak/SetPMenuText popmenu_pak/SetPMenuText
NAME
SetPMenuText - set the new constant text for a TITLED PopMenu
SYNOPSIS
SetPMenuText(pmenu, text);
PROTOTYPE
void SetPMenuText(struct PMenu *, UBYTE *);
FUNCTION
SetPMenuText sets new constant text for a PopMenu with constant
titling (TITLED bit set).
INPUTS
pmenu -- pointer to the initialized PMenu to affect
text -- UBYTE pointer to the text to render into the menu select box
RETURNS
None.
BUGS
None.
SEE ALSO
SetPMenuColor()